클라우드 다운로드 문서변환 기능
정보
클라우드 저장소(OneDrive, SharePoint, Teams)에서 다운로드 받은 문서에 대한 변환 기능을 수행합니다.
- 변환 방식에 대한 정의는 Ztcap 정책에 따릅니다.
1.개요
- 클라우드 저장소(OneDrive, SharePoint, Teams)에서 다운로드 받은 문서에 대한 변환 기능을 제공합니다.
- 변환에 대한 정책은 Ztcap 정책에 따릅니다.
2. 관련 모듈
| 파일명 | 경로 | 버전 | 설명 | 빌드 경로 |
|---|---|---|---|---|
| SCRA_DS365Shell.dll | C:\Windows\Softcamp\sdk | 6.0.0.37 | 탐색기, 브라우저, TeamsApp 훅모듈 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS6.0_VS2019(ZTCA_AIP)| |
| SCRA_DS365Shell64.dll | C:\Windows\Softcamp\sdk | 6.0.0.37 | 탐색기, 브라우저, TeamsApp 훅모듈 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS6.0_VS2019(ZTCA_AIP)| |
| SCPD_DS365.dll | C:\Windows\Softcamp\sdk\scsa | 6.1.0.4 | 문서보안 이벤트 모듈 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS6.0_VS2019(ZTCA_AIP)| |
| SCPD_DS36564.dll | C:\Windows\Softcamp\sdk\scsa | 6.1.0.4 | 문서보안 이벤트 모듈 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS6.0_VS2019(ZTCA_AIP)| |
| DSEDCon.dll | C:\Windows\Softcamp\SDS | 6.0.0.12 | 문서보안 전역모듈 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSEDCon64.dll | C:\Windows\Softcamp\SDS\x64 | 6.0.0.12 | 문서보안 전역모듈 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| SCTL_ZipMngr.dll | C:\Windows\Softcamp\SDS | 6.0.0.4 | 문서보안 Zip압축 유틸모듈 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| SCTL_ZipMngr64.dll | C:\Windows\Softcamp\SDS | 6.0.0.4 | 문서보안 Zip압축 유틸모듈 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| SDSEnc.exe | C:\Windows\Softcamp\SDS | 6.0.0.3 | 문서보안 보안문서 모듈 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSResChn.ini | C:\Windows\Softcamp\SDS | 6.0.0.3 | 다국어 리소스 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSResCht.ini | C:\Windows\Softcamp\SDS | 6.0.0.3 | 다국어 리소스 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSResCze.ini | C:\Windows\Softcamp\SDS | 6.0.0.3 | 다국어 리소스 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSResDeu.ini | C:\Windows\Softcamp\SDS | 6.0.0.3 | 다국어 리소스 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSResEng.ini | C:\Windows\Softcamp\SDS | 6.0.0.4 | 다국어 리소스 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSResFra.ini | C:\Windows\Softcamp\SDS | 6.0.0.3 | 다국어 리소스 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSResJpn.ini | C:\Windows\Softcamp\SDS | 6.0.0.4 | 다국어 리소스 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSResKor.ini | C:\Windows\Softcamp\SDS | 6.0.0.6 | 다국어 리소스 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
| DSResRus.ini | C:\Windows\Softcamp\SDS | 6.0.0.4 | 다국어 리소스 | \sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019| |
3. 관련 커스텀 정책
| ID | HOOK_LOAD_DYNAMIC 정책설명링크 |
|---|---|
| TYPE | EDIT |
| 정책값 형식 | 모듈명1;x64(0) or x86(1);로드할프로세스명 |
| 설명 | - TeamsApp의 다운로드 변환을 위한 정책 - TeamsApp의 경우 다운로드 동작을 후킹하는 프로세스가 webview2 프로세스이여서 해당 프로세스를 SCRA_DS365Shell 훅모듈을 통해 후킹해야합니다. - 아래 정책값에 포함된 DSEDCommon의 경우 SCGMEX64모듈에서 필요하여 추가되었습니다. 경우에따라서 필요 없다면 정책을 빼도 됩니다. 하지만 SCRA_DS365Shell.dll에서 후킹이 실패할 경우 필요합니다. |
| 정책 값 | DSEDCommon.dll;1;msedgewebview2.exe|DSEDCommonx64.dll;0;msedgewebview2.exe|SCRA_DS365Shell.dll;1;msedgewebview2.exe|SCRA_DS365Shell64.dll;0;msedgewebview2.exe |
4. Ztcap 정책 관련
4-1 기능 동작시 Endpoint에서 ztcap으로 질의되는 decisionFactors 예시
// 단일 문서(docx Aip문서) 다운로드시 문서에 대한 질의 json
{
"decisionFactors": [
{
"category": "document",
"target": {
"info": {
"ext": "docx",
"zoneIdentifier": "https://softcamp-my.sharepoint.com/personal/jaekwon_lee_softcamp_co_kr/_layouts/15/download.aspx?UniqueId=ed4e27ad%2Dda48%2D476b%2Da99a%2Dd517a54ad6db"
},
"type": "mip"
}
},
{
"category": "storage",
"target": {
"info": {
"folder": "%USERS%\\Downloads"
},
"type": "local"
}
},
{
"category": "fileEvent",
"target": {
"info": {
"event": "DownloadFile_FromCloud"
},
"type": "local"
}
}
]
}
// 여러문서 선택시 Zip파일에 대한 질의 json
{
"decisionFactors": [
{
"category": "document",
"target": {
"info": {
"ext": "zip",
...
"zoneIdentifier": "https://japaneast1-mediap.svc.ms/transform/zip?cs=fFNQTw"
},
"type": "zipArchive"
}
},
{
"category": "storage",
"target": {
"info": {
"folder": "%USERS%\\Downloads"
},
"type": "local"
}
},
{
"category": "fileEvent",
"target": {
"info": {
"event": "DownloadFile_FromCloud"
},
"type": "local"
}
}
]
}
4-2 ztcap 정책 설정시 주의 사항
⚠️정책 설정시 아래사항이 반드시 고려되어 Ztcap 정책이 설정되어야 기능이 동작합니다.
- decisionFactors중 category가 document인 json객체의 target.info.zoneIdentifier의 정책 설정이 필요합니다.
- decisionFactors중 category가 document인 json객체의 target.info.zoneIdentifier 의 정책값은 다운로드시 다운로드문서에 입력되는 ZoneIdentifier Url을 포함 할 수 있는 값이 설정되어야함.
- 예시 ) 다운로드 받은 문서의 Url이
https://japaneast1-mediap.svc.ms/transform/zip?cs=fFNQTw라 가정할때 Ztcap 정책에 설정 되어야 하는 decisionFactors중 category가 document인 json객체의 target.info.zoneIdentifier 의 정책값은 "*mediap.svc.ms/transform/zip*" 과 같이 Url의 일부분 앞뒤로 와일드카드(*)를 붙여 설정함.
- decisionFactors중 category가 document인 json객체의 target.type 의 정책값은 "ds"가 들어가는 것을 권장하지 않음 ( 클라우드에 DRM 문서가 있다는 가정인데 이 기능은 기본적으로 클라우드의 일반 문서 및 mip문서를 DRM 문서로 변환하기 위한 기능 )
- decisionFactors중 category가 fileEvent인 json객체의 target.info.event는 반드시 "DownloadFile_FromCloud" 값으로 설정 ( Ztcap 콘솔 정책에는 현재 미지원 )
//Ztcap 정책 예시
"category": "document",
"targets": [
{
"type": "normal",
"use": true,
"operation": "AND",
"info": {
"ext": [
"pptx",
"zip",
"xlsx",
"pdf",
"ppt",
"doc",
"xls",
"docx"
],
"zoneIdentifier": [ // 다운로드 받은 문서의 zoneidentifier url이 정책에 포함되어야함
"*microsoftonline.com*",
"*sharepoint.com*",
"*mediap.svc.ms/transform/zip*"
]
}
}
....
{
"category": "fileEvent",
"targets": [
{
"type": "local",
"use": true,
"operation": "OR",
"info": {
"event": [
"DownloadFile_FromCloud" // 파일 이벤트는 DownloadFile_FromCloud가 설정되어야함함
]
}
}
]
}
4-3 ztcap 정책 설정시 기본 포함 정책
정보
클라우드 저장소(OneDrive, SharePoint, Teams)에서 문서 다운로드 시 문서 Zone.identifier에 들어간 URL 정보가 기본적으로 ztcap 정책에 포함되어야하며, 차후 고객사나 클라우드쪽 변경사항에 따라 URL 정책의 추가가 필요할 수 있습니다.
- ztcap 정책의 아래의 URL 값이 정책으로 포함되어야합니다.
*mediap.svc.ms/transform/zip**sharepoint.com**microsoftonline.com*
클라우드 저장소 URL 정책 추가 방법
- 다운로드한 파일의 Zone.Identifier 파일 확인
# 명령 프롬프트(cmd)에서 확인
more < "filename:Zone.Identifier"
- Zone.Identifier 파일에서 확인된 URL 정보를 바탕으로 정책 추가
- ReferrerUrl 또는 HostUrl 필드의 값을 확인
- URL의 도메인 부분을 정책에 추가
- 정책 추가 시 자동으로 도메인 앞,뒤에 와일드카드(*)가 붙어 등록됩니다.
- 예시
https://example-cloud.com/download→example-cloud.com입력 →*example-cloud.com*적용 후 추가 완료
5. 적용 방법
- 모듈 패치
- Ztcap 정책 설정 ( 4. Ztcap 정책 관련 항목 적용 필수 )
- 커스텀 정책 설정
6. 제약사항
- OneDrive, SharePoint, Teams 이외의 클라우드 스토리지는 현재 미지원
- 훅 방식으로 다운로드 시점을 잡아 개발된 기능이라 아래 지원 버전 외의 브라우저나 그 이상의 브라우저에서 zoneidentifier 정보를 write하는 로직이 변경시 기능 동작이 되지 않을 수 있습니다.
| 프로그램 | 버전 |
|---|---|
| Msedge |  |
| Chrome |  |
| TeamsApp |  |
- 윈도우 및 문서보안 커스텀 정책 설정
- ZoneIdentifier 사용 On/Off 윈도우 설정(레지스트리)은 다음과 같이 설정되어야 합니다.
- 레지스트리 경로 : HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Attachments
- 레지스트리 값 : SaveZoneInformation : 2 (또는 해당 항목이 없어야 다운로드 시 문서변환 기능 동작 함)
| SaveZoneInformation 값 | Zone Identifier (MoTW) 저장 여부 | 보안 경고 표시 여부 (일반적으로) |
|---|---|---|
| 1 (Enabled) | 저장하지 않음 | 표시되지 않음 |
| 2 (Disabled/Not Configured) | 저장함 | 표시됨 |
- 문서보안 커스텀 정책
- DS_NOT_USE_SENDLOG_ZONE_IDF 커스텀 정책 0 또는 정책 미사용(제거)
- 위 커스텀 정책이 1로 설정되어 있을 경우 다운로드 되는 문서 파일에 ZoneIdentifier 등록되지 않습니다. (SaveZoneInformation : 1 설정함)
- 클라우드 다운로드 문서변환 기능은 ZoneIdentifier 등록 시점의 hooking 으로 동작합니다.
- DS_NOT_USE_SENDLOG_ZONE_IDF 커스텀 정책 0 또는 정책 미사용(제거)
7. Troubleshooting
⚠️기능 미 동작시 아래와 같은 사항을 확인하여 어떤 사항에 해당하는지 확인필요
- TeamsApp에서 미동작시
- Process Explorer등의 툴로 TeamsApp 하위 프로세스 msedgewebview2.exe에 SCRA_DS365Shell.dll이나 SCRA_DS365Shell64.dll 모듈이 로드되어있는지 확인
- 로드가 되어 있지 않은 경우 DSEDCon 버전 확인 및 커스텀 정책 적용 여부 확인
- 브라우저에서 미동작시
- Process Explorer등의 툴로 브라우저 프로세스 msedgewebview2.exe에 SCRA_DS365Shell.dll이나 SCRA_DS365Shell64.dll 모듈이 로드되어있는지 확인
- 로드가 되어 있지 않은 경우 SCRA_DS365Shell.dll 과 SCRA_DS365Shell64.dll 의 심플애드인 등록이 누락되어있는지 여부 확인 필요함.
- 공통
- SCRA_DS365Shell.dll가 정상적으로 로드되어있는 경우 다운로드 동작시 SDSMonitor 로그에 '[SCRA_DS365Shell64] Hooked_WritePrivateProfileStringW:526 L"[INFO] 조건 충족"' 이 수집되는지 확인
- SDSMonitor 로그 수집 시 로그에
[SCPD_DS365] GetZtcaPolicy:888 strLog.c_str() : '{"code":1621,"message":"Conditional policies does not exist that match the conditions"}'와 같은 로그가 수집되는 경우 ztcap 정책 설정 오류이므로 ztcap 정책을 다시 확인필요 - 해당 로그가 없거나 수집이 되어도 동작이 안될 경우 SDSMonitor 로그를 수집하여 개발자에게 전달